Skip to content

docs(conventions): define artefact-linking label convention - #146

Draft
bedirhan-yilmaz wants to merge 1 commit into
open-component-model:mainfrom
bedirhan-yilmaz:feat/artefact-linking-label-convention
Draft

docs(conventions): define artefact-linking label convention#146
bedirhan-yilmaz wants to merge 1 commit into
open-component-model:mainfrom
bedirhan-yilmaz:feat/artefact-linking-label-convention

Conversation

@bedirhan-yilmaz

@bedirhan-yilmaz bedirhan-yilmaz commented Jul 15, 2026

Copy link
Copy Markdown

What this PR does / why we need it

Adds a convention to the OCM spec for expressing cross-artefact relationships via labels. This allows a derived resource (e.g. an SBoM) to declare which subject resource it relates to within the same component version, using a structured label placed on the derived artefact.

Which issue(s) this PR is related to

Fixes open-component-model/open-delivery-gear#126

…ationships

Signed-off-by: Bedirhan Yilmaz (bedirhan-yilmaz) <bedirhan.yilmaz@sap.com>

The label value is a YAML object with the following fields:

**`artefactReference`** (required) - identifies the subject artefact within the same

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To be consistent with existing concepts like the srcRefs property, I'd suggest to rename this field to identitySelector and only allow a flat mapping of identity relevant properties, e.g.:

identitySelector:
  name: my-image
  version: 1.2.3
  architecture: amd64

Comment on lines +97 to +103
labels:
- name: odg.ocm.software/labels/artefact-ref/v1
value:
artefactReference:
name: my-image
metadata:
relation: describes

@a-thaler a-thaler Jul 24, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The label name names the semantical convention we want to define as part of the ocm spec. It should not be odg specific and should contain the convention name. The version should be moved to the version field. The values then should focus on the actual reference logic. My idea:

Suggested change
labels:
- name: odg.ocm.software/labels/artefact-ref/v1
value:
artefactReference:
name: my-image
metadata:
relation: describes
labels:
- name: ocm.software/artefactReference
version: v1
value:
identitySelector:
name: my-image
version: 1.2.3
architecture: amd64

Is the metadata really needed? If the type of the resource which has the label is sbom, isn't that already descriptive enough?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The label name names the semantical convention we want to define as part of the ocm spec.

Looking at the spec, shouldn't the label name then rather just be artefactReference?

The version should be moved to the version field.

+1

Is the metadata really needed?

I agree that we probably don't require the current metadata property. However, as also discussed in the hackathon, we will need some sort of mechanism to further specify the kind of reference (e.g. in case there are multiple SBOMs for the same artefact). I would suggest to use the extraIdentity field of the referencing artefact (here: the OCM resource for the SBoM) for this, e.g.:

resources:
  - name: my-image
    version: 1.2.3
    type: ociImage
    extraIdentity:
      foo: bar
  - name: my-image-sbom
    version: 1.2.3
    type: sbom
    extraIdentity:
      architecture: amd64
    labels:
      - name: artefactReference
        version: v1
        value:
          identitySelector:
            name: my-image
            version: 1.2.3
            foo: bar
  - name: my-image-sbom
    version: 1.2.3
    type: sbom
    extraIdentity:
      architecture: arm64
    labels:
      - name: artefactReference
        version: v1
        value:
          identitySelector:
            name: my-image
            version: 1.2.3
            foo: bar  

Wdyt about this approach?

@ChrisSchneider ChrisSchneider Jul 27, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@8R0WNI3 I think that's really good

Just asking myself: if someone puts name and version into extraIdentity, what happens?
But having something like identitySelector.extra feels too nested :/

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If someone puts name and version into extraIdentity, what happens?

According to the spec, the name may not be part of the extra identity. If the version is part of the extra identity, this does not matter (I think). To my knowledge, the component descriptors of Gardener even write the version explicitly into the extra identity, thus making the implicit contract defined in the spec explicit.

But having something like identitySelector.extra feels too nested.

I agree. Also, flattening the extra identity matches the behaviour implemented by the already existing srcRefs property.


- name: my-image-sbom
version: 1.2.3
type: application/spdx+json

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The resource type should be sbom, see

The media type of the resource access should be spdx+json

version: 1.2.3
type: application/spdx+json
labels:
- name: odg.ocm.software/labels/artefact-ref/v1

@ChrisSchneider ChrisSchneider Jul 27, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would suggest to just name it ocm.software/artefact-ref

The linking will be part of OCM core, used by other tooling and not only ODG

There is also a dedicated version property for OCM labels, see: https://github.com/open-component-model/ocm-spec/blob/main/doc/01-model/03-elements-sub.md#labels


- name: my-image-sbom
version: 1.2.3
type: application/spdx+json

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From my understanding type would be sbom, and application/spdx+json would become the file's mediaType

See: https://ocm.software/docs/reference/input-and-access-types/#filev1

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Define OCM artefact reference label contract

4 participants